home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 August: Tool Chest / Dev.CD Aug 94.toast / Sample Code / MoreFiles 1.1.1 / !MoreFiles Read Me next >
Encoding:
Text File  |  1994-02-01  |  8.9 KB  |  117 lines  |  [TEXT/ttxt]
  1. MoreFiles
  2. ---------
  3.  
  4. A collection of File Manager (and related) routines
  5. by Jim Luther, Apple Developer Technical Support
  6.  
  7. •••••••••• What is MoreFiles? ••••••••••
  8.  
  9. MoreFiles is a collection of high-level routines written over the last couple of years to answer File Manager questions developers have sent to Apple Developer Technical Support.  The routines have been tested (but not stress-tested), documented, code-reviewed, and used in my own programs.
  10.  
  11. Important Note
  12. --------------
  13. These routines are meant to be used from an application environment. In particular, some routines use static variables which require an A5 world and almost all routines make calls that that are unsafe at interrupt time (i.e., synchronous File Manager calls and Memory Manager calls). If you plan to use these routines from stand-alone code modules, you may need to make some modifications to the code that uses static variables.  Don't even think about using these routines from code that executes at interrupt time.
  14.  
  15. MoreFiles currently consists of the following files:
  16.  
  17. MoreFiles.c - the “glue code” for high-level and FSSpec style routines that were never implemented or added to the standard interface for one reason or another.  If you're uncomfortable filling in parameter blocks, you'll find the code in this file very useful.
  18.  
  19. MoreFiles.h and MoreFiles.p - the documentation and header files for calling the routines included in MoreFiles.c.
  20.  
  21. Sharing.h and Sharing.p - the inline “glue code” for calling the AppleShare server routines, PBShare, PBUnshare, and PBGetUGEntry. These routines have been added to Files.h in the Universal Interfaces so they aren't used by MoreFiles.  However, I've left them here in case you're still using the old interfaces.
  22.  
  23. MoreFilesExtras.c - a collection of useful File Manager utility routines for everything from searching a volume with CatSearch to making a file invisible.
  24.  
  25. MoreFilesExtras.h and MoreFilesExtras.p - the documentation and header files for calling the routines included in MoreFilesExtras.c.  I recommend that you browse through the header files - you'll probably find a routine that you've always wanted.
  26.  
  27. FileCopy.c - a robust, general purpose file copy routine that does everything the right way.  Copying a file on the Macintosh isn't as simple as you'd think if you want to handle all cases (i.e., file server drop boxes, preflighting disk space, etc.).  This routine does it all and is fast, too.
  28.  
  29. FileCopy.h and FileCopy.p - the documentation and header files for calling the routines included in FileCopy.c.
  30.  
  31. DirectoryCopy.c - a general purpose recursive directory copy routine with a hook for your error handling routine.
  32.  
  33. DirectoryCopy.h and DirectoryCopy.p - the documentation and header files for calling the routines included in DirectoryCopy.c.
  34.  
  35. FSpCompat.c - the “glue code” for FSSpec style routines that will work under System 6 as much as possible.  If you still need to support System 6, you'll find the code in this file very useful.
  36.  
  37. FSpCompat.h and FSpCompat.p -  the header files for calling the routines included in FSpCompat.c.  FSpCompat.h and FSpCompat.p do not document the calls - they only list the differences (if any) from the behavior of the real FSSpec calls. Read Inside Macintosh for the documentation to the real FSSpec calls.
  38.  
  39. MoreFiles.π - the THINK C project file you can use to build a THINK library.
  40.  
  41. MoreFiles.lib - the library built with THINK C version 6.0.1. The library is supplied two ways, with and without MacsBug debugger labels.  Use the library with labels to help you debug; use the library without labels for smaller code.
  42.  
  43. MoreFilesLib.o - the library built with MPW C version 3.3.1 and MPW LIB version 3.3.1. The library is supplied two ways, with and without MacsBug debugger labels.  Use the library with labels to help you debug; use the library without labels for smaller code.
  44.  
  45. FindFolderGlue.o - a library containing the FindFolder compatibility glue.  This library is needed only by THINK Pascal users.
  46.  
  47. Worksheet - the MPW worksheet used to compile and build the MPW version of the libraries.
  48.  
  49. •••••••••• How you use MoreFiles? ••••••••••
  50.  
  51. You can compile the code, put it in a library (or use the precompiled libraries), and link it into your programs.  You can cut and paste it into your programs.  You can use it as example code.  Feel free to rip it off in whatever ways you find work best for you.
  52.  
  53. All routines use Pascal calling conventions so this code can be used from either C or Pascal.
  54.  
  55. You'll also notice that all routines that make other File Manager calls return an OSErr result.  I always check for error results and you should too.
  56.  
  57.  
  58. •••••••••• Documentation ••••••••••
  59.  
  60. The documentation for the routines can be found in the header files.  There, you'll find a short description of each call and a complete listing of all input and output parameters.  For example, here's the documentation for one of the routines, GetFileLocation.
  61.  
  62. /******************************************************************/
  63.  
  64. pascal    OSErr    GetFileLocation(short refNum,
  65.                                    short *vRefNum,
  66.                                    long *dirID,
  67.                                    StringPtr fileName);
  68. /*  Use GetFileLocation to get the location (volume reference number,
  69.     directory ID, and fileName) of an open file.
  70.  
  71.     refNum     input:    The file reference number of an open file.
  72.     vRefNum   output:  The volume reference number.
  73.     dirID         output:  The parent directory ID.
  74.     fileName  input:     Points to a buffer (minimum Str63) where the
  75.                                   filename is to be returned or must be nil.
  76.                      output:  The filename.
  77. */
  78.  
  79. /******************************************************************/
  80.  
  81. Some routines have very few comments in their code because they simply make a single File Manager call.  For those routines, the routine description is the comment.  However, you'll find that more complicated routines have plenty of comments to clarify what and why the code is doing something.  If something isn't clear, take a look at Inside Macintosh: Files for further reference.
  82.  
  83. •••••••••• Release Notes ••••••••••
  84.  
  85. v1.0  09/14/93
  86. •  First release for Developer CD
  87.  
  88. v1.1  01/22/94
  89. •  MoreFiles is now built with the Universal Interfaces.
  90. •  Gave DirectoryCopy.p and MoreFilesExtras.p the correct UNIT names.
  91. •  Built MoreFiles.lib with THINK C and MoreFilesLib.o with MPW C.
  92. •  Changed the way the GetFilenameFromPathname works function (I made it work correctly for its intended purpose).
  93. •  Added GetObjectLocation function to MoreFilesExtras.
  94. •  Moved local constants from FileCopy.h to FileCopy.c.
  95. •  Moved local constants from DirectoryCopy.h to DirectoryCopy.c.
  96. •  Added Sharing.p. to go along with Sharing.h, but then didn't need either because the Universal Interfaces now include Share, Unshare, and GetUGEntry in Files.h.
  97. •  Added standard disclaimer to all source files.
  98. •  Fixed bug in FSpMoveRename function (it called HCopyFile instead of HMoveRename).
  99. •  Added HMoveRenameCompat and FSpMoveRenameCompat functions to MoreFilesExtras.
  100. •  Changed HOpenAware and HOpenRFAware functions in MoreFilesExtras to work around a bug in Foreign File Access (FFA) based foreign file systems (ISO 9960, High Sierra, Audio, Photo CD Access, etc.). FFA based file systems incorrectly return a wPrErr result to the OpenDeny calls instead of a paramErr result.
  101. •  Added UnmountAndEject function to MoreFilesExtras.
  102. •  The ChangeCreatorType and ChangeFDFlags functions in MoreFilesExtras no longer try (and fail) to use BumpDate on fsRtParID.
  103. •  Added DeleteDirectoryContents and DeleteDirectory functions to MoreFilesExtras.
  104. •  Removed DTS.Lib StringUtils files. The only function needed by MoreFiles was pcpy, so I dropped it into the MoreFiles sources as a static function rather than force you to include all of StringUtils.
  105. •  Fixed conditional #include in MoreFilesExtras.c.
  106. •  In MoreFilesExtras.h, changed macros for checking volume attribute bits to shift the 1L constant rather than the vMAttrib field in the GetVolParmsInfoBuffer. This produces tighter code.
  107. •  Added FSpCompat.c, FSpCompat.h, and FSpCompat.p.  The FSpCompat functions let you use the System 7 FSSpec calls under System 6 (the functions use the same calling conventions as the System 7 FSSpec calls but have a modified name (for example, FSpCreate is FSpCreateCompat).
  108. •  Ran all sources through as many C compilers as possible and made minor modifications to all sources in an attempt to get rid of most warnings. There are still a couple left to fix, but I'm up against the deadline for the next Developer CD, so they'll have to wait…
  109.  
  110. v1.1.1  02/01/94
  111. • Added FindFolderGlue.o and its Read Me file to the Libraries folder for THINK Pascal users.
  112.  
  113. Thanks (you know who you are) for the bug reports and suggestions that helped me improve MoreFiles since the last version. If you find any more bugs or have any comments, please let me know at:
  114. AppleLink: DEVFEEDBACK
  115. Internet: DEVFEEDBACK@AppleLink.Apple.com
  116. Please put "Attn: Jim Luther" in the message title.
  117.